<!DOCTYPE HTML>
<html><head><title>Alkaline Documentation</title><script type="text/javascript">
	function makeTOC() {
		var div = document.getElementById('toc');
		var toc = [];
		var list = [], i, l, items;
		items = document.getElementsByTagName('h2');
		for (i = 0, l = items.length; i < l; i++)
			list[i] = items[i];
		for (i = 0; i < l; i++) {
			toc.push('<a href="#toc' + (i + 1) + '">' + (i + 1) + '. ' + list[i].innerHTML + '</a>');
			var a = document.createElement('a');
			a.name = 'toc' + (i + 1);
			list[i].parentNode.insertBefore(a, list[i]);
			list[i].innerHTML = (i + 1) + '. ' + list[i].innerHTML;
		}
		div.innerHTML = toc.join('<br />');
	}
</script><style type="text/css"">
	td {
		vertical-align: top;
	}
	.code {
		font-family: Courier New, monospace;
	}
</style></head><body onload="makeTOC()">
	<h1>Alkaline Documentation</h1>
	<div id="toc">JavaScript is required in order to generate the Table Of Contents.</div>
	<h2>Description</h2>
		<p>Alkaline is a set of ECMAScript libraries designed to implement ECMAScript 5 and the lastest JavaScript specification
			on top of the baseline ECMAScript 3 implemented by browsers. This way it is possible, for instance,
			to write code using the latest standard and use this layer on top of browsers which do not implement it yet, while still
			benefiting from the full speed of browsers which are up to date.</p>
		<p><s>Alkaline has two parts: a parser (generated by ANTLR, which is also available in Java for debug purposes and unit testing
			with gunit) and a runtime library and interpretor which can either interpret the parsed tree or generate javascript code
			which uses only basic javascript instructions and is supported by all browsers.</s></p>
		<p>Another use case for Alkaline will be to analyze JavaScript source files in order to find common mistakes such as assigning an
			undefined variable (which creates a new global variable), missing semicolon, unclosed parantheses and more.</p>
	<h2>Processing stages</h2>
		<p>Lexer -> Parser -> Modules* -> Generator</p>
		<p>When processing, the user can select any number of modules. If the user does not choose any modules then the code is just reformatted and comments are removed.</p>
	<h2>Modules</h2>
		<p>Modules are components which analyse or alter the code parsed. They receive an Abstract Syntax Tree and output either a new AST or the same one after modifying it.</p>
		<p>The following modules are offered in the Alkaline package:</p>
		<h3>Analyser</h3>
			<p>This module searches for common mistakes and optimization posibilities. It may also minify the text (e.g. by renaming variables).</p>
		<h3>5to3</h3>
			<p>This module transforms EcmaScript 5 and Javascript 1.8.1 constructs into EcmaScript 3 statements.</p>
	<h2>The Parser and Lexer</h2>
		<h3>Current status</h3>
			<p>Currently the parser and lexer fave full support for EcmaScript 5. Support for JavaScript 1.6-1.8.1 is currently incomplete.</p>
			<p>This includes:</p>
			<ul>
				<li>support for literals:
					<ul>
						<li>null</li>
						<li>undefined</li>
						<li>strings: "asd", 'abc', 'cr\rlf\n'</li>
						<li>numbers: 0, 1, .2, 3e+2, .1E-3</li>
						<li>booleans: false, true</li>
						<li>arrays: [1, 2]</li>
						<li>objects: {a: 1, 'b': [2, 3]}</li>
						<li>regular expressions: /asdf/, /as(df)?/g</li>
					</ul></li>
				<li>variable declaration: "var a;", "var a, b;", "var a = 3;"</li>
				<li>expressions: "2+3", "a - 4", "3 + ' monkeys'", "1 + (3 - 2)"</li>
				<li>complex items: "a[3]", "b.asd", "c.next()[2]"</li>
				<li>conditionals, loops and flow control: if, for, for-in, for-each-in, while, do...while, switch, break, continue</li>
				<li>labels for statements: "breakMe: while(1) { while(2) { break breakMe; } }"</li>
				<li>and more</li>
			</ul>
	<h2>The AST generated</h2>
		<p>The AST is composed of a few virtual tokens which are tightly related to language structures and language items</p>
		Virtual tokens:
		<ul>
			<li>BLOCK - a block of instructions (may be empty)</li>
			<li>EXPR - an expression (has at least one item)</li>
			<li>ArgDecl - list of arguments for a function, may be empty</li>
			<li>ITEM - an item, composed of a base (first child, references a literal or variable) and zero or more tails (such as
				function call, array index or property selection - "object.property")</li>
			<li>OBJECT, ARRAY - used for literals</li>
		</ul>
		Language items:
		<ul>
			<li>literals: RegExp, Id, Number, String, True, False, Null, Undefined</li>
			<li>language constructs: If, Else, While, Do, Try, Catch, etc.</li>
		</ul>
	<h2>GUnit</h2>
		<p>The grammar is tested with many unit tests using GUnit (GUnit ships with ANTLR).</p>
		<p>The tests target both lexer rules, parser rules and invalid syntax.</p>
		<p>So far there are 280 unit tests targetting the main part. All tests can be ran in both the Java target and the JavaScript target.</p>
		<p>In the future, tests for the resulting AST will be written (when it will stabilize).</p>
	<h2>The Runtime libraries</h2>
		<p>Not done yet</p>
	<h2>Instructions supported</h2>
		<table><thead><tr>
			<th>Instructions</th><th>Example(s)</th><th>Description</th>
		</tr></thead><tbody>
			<tr><td>operations</td><td class="code">a+b; 2 != 3; 2 !== '2'; c++; x = 3;</td><td>basic operations with variables and constants</td></tr>
			<tr><td>select property</td><td class="code">object.count++; limit.max-limit.min; limit["can overflow"];</td><td>select a property from an object</td></tr>
			<tr><td>function calls</td><td class="code">print(); alert("Hello World!"); window.close(); window1.close.call(window2, "now");</td><td>call a function</td></tr>
			<tr><td>declare variables</td><td>global/function variable: <span class="code">var a, b = 2, c = b;</span><br />block-level: <span class="code">let x = 5;</span></td><td>declare one or more variables with function-scope or block-scope</td></tr>
			<tr><td>supported literal types</td><td>
				<span class="code">null</span><br />
				Strings: <span class="code">"", 'asdf', "qwerty"</span><br />
				Numbers: <span class="code">0, 123, -3, 4.5, 3e+4</span><br />
				Booleans: <span class="code">true, false</span><br />
				RegExp: <span class="code">/\s*/, /case\s+insensitive/i, /^multi-line.*/m, /match all/g</span><br />
				Arrays: <span class="code">[], [1], [1, 2], [1, , 3], [1,]</span><br />
				Objects: <span class="code">{}, { sender: "john@example.com", destination: "jack@example.com" }</span>
				</td><td></td></tr>
			<tr><td colspan="3">...TO FINISH...</td></tr>
		</tbody></table>
	<h2>Glossary</h2>
		<dl>
			<dt>JavasSript</dt><dd>EcmaScript dialect. Used in the Mozilla Firefox browser (for both web pages and plugins), Rhino (Java port of the JS engine in Firefox), Adobe Flash and other products. Originated in Netscape Navigator before EcmaScript was standardized.</dd>
			<dt>JScript</dt><dd>EcmaScript dialect used by Microsoft. This is present in Internet Explorer and Windows Scripting Host.</dd>
		</dl>
</body></html>